home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / Interfaces&Libraries / Universal / Interfaces / AIncludes / NameRegistry.a < prev    next >
Encoding:
Text File  |  1998-08-17  |  15.1 KB  |  561 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        NameRegistry.a
  3. ;
  4. ;    Contains:    NameRegistry Interfaces
  5. ;
  6. ;    Version:    Technology:    MacOS
  7. ;                Release:    Universal Interfaces 3.2
  8. ;
  9. ;    Copyright:    © 1993-1998 by Apple Computer, Inc., all rights reserved.
  10. ;
  11. ;    Bugs?:        For bug reports, consult the following page on
  12. ;                the World Wide Web:
  13. ;
  14. ;                    http://developer.apple.com/bugreporter/
  15. ;
  16. ;
  17.     IF &TYPE('__NAMEREGISTRY__') = 'UNDEFINED' THEN
  18. __NAMEREGISTRY__ SET 1
  19.  
  20.     IF &TYPE('__MACTYPES__') = 'UNDEFINED' THEN
  21.     include 'MacTypes.a'
  22.     ENDIF
  23.  
  24. ; *******************************************************************************
  25. ; * 
  26. ; * Foundation Types
  27. ; *
  28. ; 
  29.  
  30. ;  Value of a property 
  31. ; typedef void *                        RegPropertyValue
  32.  
  33. ;  Length of property value 
  34. ; typedef UInt32                         RegPropertyValueSize
  35.  
  36. ; *******************************************************************************
  37. ; * 
  38. ; * RegEntryID    :    The Global x-Namespace Entry Identifier
  39. ; *
  40. ; 
  41.  
  42. RegEntryID                RECORD 0
  43. contents                 ds.l    4                ; offset: $0 (0)
  44. sizeof                     EQU *                    ; size:   $10 (16)
  45.                         ENDR
  46. ; typedef struct RegEntryID *            RegEntryIDPtr
  47.  
  48. ; *******************************************************************************
  49. ; *
  50. ; * Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  51. ; *
  52. ; *    • Names are a colon-separated list of name components.  Name components
  53. ; *      may not themselves contain colons.  
  54. ; *    • Names are presented as null-terminated ASCII character strings.
  55. ; *    • Names follow similar parsing rules to Apple file system absolute
  56. ; *      and relative paths.  However the '::' parent directory syntax is
  57. ; *      not currently supported.
  58. ; 
  59.  
  60. ;  Max length of Entry Name 
  61.  
  62. kRegCStrMaxEntryNameLength        EQU        47
  63. ;  Entry Names are single byte ASCII 
  64. ; typedef char                             RegCStrEntryName
  65.  
  66. ; typedef char *                        RegCStrEntryNamePtr
  67.  
  68. ;  length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1
  69. RegCStrEntryNameBuf        RECORD 0
  70. elements                 ds.b    48
  71. sizeof                     EQU *                    ; size:   $30 (48)
  72.                         ENDR
  73.  
  74.  
  75. ; typedef char                             RegCStrPathName
  76.  
  77. ; typedef UInt32                         RegPathNameSize
  78.  
  79.  
  80. kRegPathNameSeparator            EQU        58                    ; 0x3A 
  81. kRegEntryNameTerminator            EQU        $00                    ; '\0' 
  82. kRegPathNameTerminator            EQU        $00                    ; '\0' 
  83. ; *******************************************************************************
  84. ; *
  85. ; * Property Name and ID Definitions
  86. ; *    (Applies to all Properties Regardless of NameSpace)
  87. ; 
  88.  
  89.  
  90. kRegMaximumPropertyNameLength    EQU        31                    ; Max length of Property Name 
  91. kRegPropertyNameTerminator        EQU        $00                    ; '\0' 
  92. RegPropertyNameBuf        RECORD 0
  93. elements                 ds.b    32
  94. sizeof                     EQU *                    ; size:   $20 (32)
  95.                         ENDR
  96.  
  97.  
  98. ; typedef char                             RegPropertyName
  99.  
  100. ; typedef char *                        RegPropertyNamePtr
  101.  
  102. ; *******************************************************************************
  103. ; *
  104. ; * Iteration Operations
  105. ; *
  106. ; *    These specify direction when traversing the name relationships
  107. ; 
  108.  
  109. ; typedef UInt32                         RegIterationOp
  110.  
  111. ; typedef RegIterationOp                 RegEntryIterationOp
  112.  
  113.  
  114.                                                             ; Absolute locations
  115. kRegIterRoot                    EQU        $00000002            ; "Upward" Relationships    
  116. kRegIterParents                    EQU        $00000003            ; include all  parent(s) of entry 
  117.                                                             ; "Downward" Relationships
  118. kRegIterChildren                EQU        $00000004            ; include all children 
  119. kRegIterSubTrees                EQU        $00000005            ; include all sub trees of entry 
  120. kRegIterDescendants                EQU        $00000005            ; include all descendants of entry 
  121.                                                             ; "Horizontal" Relationships    
  122. kRegIterSibling                    EQU        $00000006            ; include all siblings 
  123.                                                             ; Keep doing the same thing
  124. kRegIterContinue                EQU        $00000001
  125. ; *******************************************************************************
  126. ; *
  127. ; * Name Entry and Property Modifiers
  128. ; *
  129. ; *
  130. ; *
  131. ; * Modifiers describe special characteristics of names
  132. ; * and properties.  Modifiers might be supported for
  133. ; * some names and not others.
  134. ; * 
  135. ; * Device Drivers should not rely on functionality
  136. ; * specified as a modifier.
  137. ; 
  138.  
  139. ; typedef UInt32                         RegModifiers
  140.  
  141. ; typedef RegModifiers                     RegEntryModifiers
  142.  
  143. ; typedef RegModifiers                     RegPropertyModifiers
  144.  
  145.  
  146. kRegNoModifiers                    EQU        $00000000            ; no entry modifiers in place 
  147. kRegUniversalModifierMask        EQU        $0000FFFF            ; mods to all entries 
  148. kRegNameSpaceModifierMask        EQU        $00FF0000            ; mods to all entries within namespace 
  149. kRegModifierMask                EQU        $FF000000            ; mods to just this entry 
  150. ;  Universal Property Modifiers 
  151.  
  152. kRegPropertyValueIsSavedToNVRAM    EQU        $00000020            ; property is non-volatile (saved in NVRAM) 
  153. kRegPropertyValueIsSavedToDisk    EQU        $00000040            ; property is non-volatile (saved on disk) 
  154. ;  ///////////////////////
  155. ;//
  156. ;// The Registry API
  157. ;//
  158. ;/////////////////////// 
  159.  
  160. ;  ///////////////////////
  161. ;//
  162. ;// Entry Management
  163. ;//
  164. ;/////////////////////// 
  165.  
  166.  
  167. ; -------------------------------
  168. ; * EntryID handling
  169. ; 
  170.  
  171. ; 
  172. ; * Initialize an EntryID to a known invalid state
  173. ; *   note: invalid != uninitialized
  174. ; 
  175.  
  176. ;
  177. ; extern OSStatus RegistryEntryIDInit(RegEntryID *id)
  178. ;
  179.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  180.         IMPORT_CFM_FUNCTION RegistryEntryIDInit
  181.     ENDIF
  182.  
  183. ; 
  184. ; * Compare EntryID's for equality or if invalid
  185. ; *
  186. ; * If a NULL value is given for either id1 or id2, the other id 
  187. ; * is compared with an invalid ID.  If both are NULL, the id's 
  188. ; * are consided equal (result = true). 
  189. ; 
  190.  
  191. ;
  192. ; extern Boolean RegistryEntryIDCompare(const RegEntryID *id1, const RegEntryID *id2)
  193. ;
  194.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  195.         IMPORT_CFM_FUNCTION RegistryEntryIDCompare
  196.     ENDIF
  197.  
  198. ; 
  199. ; * Copy an EntryID
  200. ; 
  201.  
  202. ;
  203. ; extern OSStatus RegistryEntryIDCopy(const RegEntryID *src, RegEntryID *dst)
  204. ;
  205.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  206.         IMPORT_CFM_FUNCTION RegistryEntryIDCopy
  207.     ENDIF
  208.  
  209. ; 
  210. ; * Free an ID so it can be reused.
  211. ; 
  212.  
  213. ;
  214. ; extern OSStatus RegistryEntryIDDispose(RegEntryID *id)
  215. ;
  216.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  217.         IMPORT_CFM_FUNCTION RegistryEntryIDDispose
  218.     ENDIF
  219.  
  220. ; -------------------------------
  221. ; * Adding and removing entries
  222. ; *
  223. ; * If (parentEntry) is NULL, the name is assumed
  224. ; * to be a rooted path. It is rooted to an anonymous, unnamed root.
  225. ; 
  226.  
  227. ;
  228. ; extern OSStatus RegistryCStrEntryCreate(const RegEntryID *parentEntry, const RegCStrPathName *name, RegEntryID *newEntry)
  229. ;
  230.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  231.         IMPORT_CFM_FUNCTION RegistryCStrEntryCreate
  232.     ENDIF
  233.  
  234. ;
  235. ; extern OSStatus RegistryEntryDelete(const RegEntryID *id)
  236. ;
  237.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  238.         IMPORT_CFM_FUNCTION RegistryEntryDelete
  239.     ENDIF
  240.  
  241. ;
  242. ; extern OSStatus RegistryEntryCopy(RegEntryID *parentEntryID, RegEntryID *sourceDevice, RegEntryID *destDevice)
  243. ;
  244.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  245.         IMPORT_CFM_FUNCTION RegistryEntryCopy
  246.     ENDIF
  247.  
  248. ; ---------------------------
  249. ; * Traversing the namespace
  250. ; *
  251. ; * To support arbitrary namespace implementations in the future,
  252. ; * I have hidden the form that the place pointer takes.  The previous
  253. ; * interface exposed the place pointer by specifying it as a
  254. ; * RegEntryID.
  255. ; *
  256. ; * I have also removed any notion of returning the entries
  257. ; * in a particular order, because an implementation might
  258. ; * return the names in semi-random order.  Many name service
  259. ; * implementations will store the names in a hashed lookup
  260. ; * table.
  261. ; *
  262. ; * Writing code to traverse some set of names consists of
  263. ; * a call to begin the iteration, the iteration loop, and
  264. ; * a call to end the iteration.  The begin call initializes
  265. ; * the iteration cookie data structure.  The call to end the 
  266. ; * iteration should be called even in the case of error so 
  267. ; * that allocated data structures can be freed.
  268. ; *
  269. ; *    Create(...)
  270. ; *    do {
  271. ; *        Iterate(...);
  272. ; *    } while (!done);
  273. ; *    Dispose(...);
  274. ; *
  275. ; * This is the basic code structure for callers of the iteration
  276. ; * interface.
  277. ; 
  278.  
  279.  
  280.  
  281. ;  
  282. ; * create/dispose the iterator structure
  283. ; *   defaults to root with relationship = kRegIterDescendants
  284. ; 
  285.  
  286. ;
  287. ; extern OSStatus RegistryEntryIterateCreate(RegEntryIter *cookie)
  288. ;
  289.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  290.         IMPORT_CFM_FUNCTION RegistryEntryIterateCreate
  291.     ENDIF
  292.  
  293. ;
  294. ; extern OSStatus RegistryEntryIterateDispose(RegEntryIter *cookie)
  295. ;
  296.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  297.         IMPORT_CFM_FUNCTION RegistryEntryIterateDispose
  298.     ENDIF
  299.  
  300. ;  
  301. ; * set Entry Iterator to specified entry
  302. ; 
  303.  
  304. ;
  305. ; extern OSStatus RegistryEntryIterateSet(RegEntryIter *cookie, const RegEntryID *startEntryID)
  306. ;
  307.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  308.         IMPORT_CFM_FUNCTION RegistryEntryIterateSet
  309.     ENDIF
  310.  
  311. ; 
  312. ; * Return each value of the iteration
  313. ; *
  314. ; * return entries related to the current entry
  315. ; * with the specified relationship
  316. ; 
  317.  
  318. ;
  319. ; extern OSStatus RegistryEntryIterate(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done)
  320. ;
  321.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  322.         IMPORT_CFM_FUNCTION RegistryEntryIterate
  323.     ENDIF
  324.  
  325. ; 
  326. ; * return entries with the specified property
  327. ; *
  328. ; * A NULL RegPropertyValue pointer will return an
  329. ; * entry with the property containing any value.
  330. ; 
  331.  
  332. ;
  333. ; extern OSStatus RegistryEntrySearch(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize)
  334. ;
  335.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  336.         IMPORT_CFM_FUNCTION RegistryEntrySearch
  337.     ENDIF
  338.  
  339. ; --------------------------------
  340. ; * Find a name in the namespace
  341. ; *
  342. ; * This is the fast lookup mechanism.
  343. ; * NOTE:  A reverse lookup mechanism
  344. ; *      has not been provided because
  345. ; *        some name services may not
  346. ; *        provide a fast, general reverse
  347. ; *        lookup.
  348. ; 
  349.  
  350. ;
  351. ; extern OSStatus RegistryCStrEntryLookup(const RegEntryID *searchPointID, const RegCStrPathName *pathName, RegEntryID *foundEntry)
  352. ;
  353.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  354.         IMPORT_CFM_FUNCTION RegistryCStrEntryLookup
  355.     ENDIF
  356.  
  357. ; ---------------------------------------------
  358. ; * Convert an entry to a rooted name string
  359. ; *
  360. ; * A utility routine to turn an Entry ID
  361. ; * back into a name string.
  362. ; 
  363.  
  364. ;
  365. ; extern OSStatus RegistryEntryToPathSize(const RegEntryID *entryID, RegPathNameSize *pathSize)
  366. ;
  367.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  368.         IMPORT_CFM_FUNCTION RegistryEntryToPathSize
  369.     ENDIF
  370.  
  371. ;
  372. ; extern OSStatus RegistryCStrEntryToPath(const RegEntryID *entryID, RegCStrPathName *pathName, RegPathNameSize pathSize)
  373. ;
  374.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  375.         IMPORT_CFM_FUNCTION RegistryCStrEntryToPath
  376.     ENDIF
  377.  
  378. ; 
  379. ; * Parse a path name.
  380. ; *
  381. ; * Retrieve the last component of the path, and
  382. ; * return a spec for the parent.
  383. ; 
  384.  
  385. ;
  386. ; extern OSStatus RegistryCStrEntryToName(const RegEntryID *entryID, RegEntryID *parentEntry, RegCStrEntryName *nameComponent, Boolean *done)
  387. ;
  388.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  389.         IMPORT_CFM_FUNCTION RegistryCStrEntryToName
  390.     ENDIF
  391.  
  392. ;  //////////////////////////////////////////////////////
  393. ;//
  394. ;// Property Management
  395. ;//
  396. ;////////////////////////////////////////////////////// 
  397.  
  398. ; -------------------------------
  399. ; * Adding and removing properties
  400. ; 
  401.  
  402. ;
  403. ; extern OSStatus RegistryPropertyCreate(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize)
  404. ;
  405.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  406.         IMPORT_CFM_FUNCTION RegistryPropertyCreate
  407.     ENDIF
  408.  
  409. ;
  410. ; extern OSStatus RegistryPropertyDelete(const RegEntryID *entryID, const RegPropertyName *propertyName)
  411. ;
  412.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  413.         IMPORT_CFM_FUNCTION RegistryPropertyDelete
  414.     ENDIF
  415.  
  416. ;
  417. ; extern OSStatus RegistryPropertyRename(const RegEntryID *entry, const RegPropertyName *oldName, const RegPropertyName *newName)
  418. ;
  419.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  420.         IMPORT_CFM_FUNCTION RegistryPropertyRename
  421.     ENDIF
  422.  
  423. ; ---------------------------
  424. ; * Traversing the Properties of a name
  425. ; *
  426. ; 
  427.  
  428.  
  429.  
  430. ;
  431. ; extern OSStatus RegistryPropertyIterateCreate(const RegEntryID *entry, RegPropertyIter *cookie)
  432. ;
  433.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  434.         IMPORT_CFM_FUNCTION RegistryPropertyIterateCreate
  435.     ENDIF
  436.  
  437. ;
  438. ; extern OSStatus RegistryPropertyIterateDispose(RegPropertyIter *cookie)
  439. ;
  440.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  441.         IMPORT_CFM_FUNCTION RegistryPropertyIterateDispose
  442.     ENDIF
  443.  
  444. ;
  445. ; extern OSStatus RegistryPropertyIterate(RegPropertyIter *cookie, RegPropertyName *foundProperty, Boolean *done)
  446. ;
  447.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  448.         IMPORT_CFM_FUNCTION RegistryPropertyIterate
  449.     ENDIF
  450.  
  451. ; 
  452. ; * Get the value of the specified property for the specified entry.
  453. ; *
  454. ; 
  455.  
  456. ;
  457. ; extern OSStatus RegistryPropertyGetSize(const RegEntryID *entryID, const RegPropertyName *propertyName, RegPropertyValueSize *propertySize)
  458. ;
  459.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  460.         IMPORT_CFM_FUNCTION RegistryPropertyGetSize
  461.     ENDIF
  462.  
  463. ; 
  464. ; * (*propertySize) is the maximum size of the value returned in the buffer
  465. ; * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  466. ; * value returned.
  467. ; 
  468.  
  469. ;
  470. ; extern OSStatus RegistryPropertyGet(const RegEntryID *entryID, const RegPropertyName *propertyName, void *propertyValue, RegPropertyValueSize *propertySize)
  471. ;
  472.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  473.         IMPORT_CFM_FUNCTION RegistryPropertyGet
  474.     ENDIF
  475.  
  476. ;
  477. ; extern OSStatus RegistryPropertySet(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize)
  478. ;
  479.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  480.         IMPORT_CFM_FUNCTION RegistryPropertySet
  481.     ENDIF
  482.  
  483. ;  //////////////////////////////////////////////////////
  484. ;//
  485. ;// Modifier Management
  486. ;//
  487. ;////////////////////////////////////////////////////// 
  488.  
  489. ; 
  490. ; * Modifiers describe special characteristics of names
  491. ; * and properties.  Modifiers might be supported for
  492. ; * some names and not others.
  493. ; * 
  494. ; * Device Drivers should not rely on functionality
  495. ; * specified as a modifier.  These interfaces
  496. ; * are for use in writing Experts.
  497. ; 
  498.  
  499. ; 
  500. ; * Get and Set operators for entry modifiers
  501. ; 
  502.  
  503. ;
  504. ; extern OSStatus RegistryEntryGetMod(const RegEntryID *entry, RegEntryModifiers *modifiers)
  505. ;
  506.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  507.         IMPORT_CFM_FUNCTION RegistryEntryGetMod
  508.     ENDIF
  509.  
  510. ;
  511. ; extern OSStatus RegistryEntrySetMod(const RegEntryID *entry, RegEntryModifiers modifiers)
  512. ;
  513.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  514.         IMPORT_CFM_FUNCTION RegistryEntrySetMod
  515.     ENDIF
  516.  
  517. ; 
  518. ; * Get and Set operators for property modifiers
  519. ; 
  520.  
  521. ;
  522. ; extern OSStatus RegistryPropertyGetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers *modifiers)
  523. ;
  524.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  525.         IMPORT_CFM_FUNCTION RegistryPropertyGetMod
  526.     ENDIF
  527.  
  528. ;
  529. ; extern OSStatus RegistryPropertySetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers modifiers)
  530. ;
  531.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  532.         IMPORT_CFM_FUNCTION RegistryPropertySetMod
  533.     ENDIF
  534.  
  535. ; 
  536. ; * Iterator operator for entry modifier search
  537. ; 
  538.  
  539. ;
  540. ; extern OSStatus RegistryEntryMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegEntryModifiers matchingModifiers)
  541. ;
  542.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  543.         IMPORT_CFM_FUNCTION RegistryEntryMod
  544.     ENDIF
  545.  
  546. ; 
  547. ; * Iterator operator for entries with matching 
  548. ; * property modifiers
  549. ; 
  550.  
  551. ;
  552. ; extern OSStatus RegistryEntryPropertyMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegPropertyModifiers matchingModifiers)
  553. ;
  554.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  555.         IMPORT_CFM_FUNCTION RegistryEntryPropertyMod
  556.     ENDIF
  557.  
  558.  
  559.     ENDIF ; __NAMEREGISTRY__ 
  560.  
  561.